home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1993 / Internet Info CD-ROM (Walnut Creek) (1993).iso / networking / terms / kermit / d / k20cmd.doc < prev    next >
Encoding:
Text File  |  1988-08-16  |  8.8 KB  |  315 lines
  1.  
  2.  
  3.  
  4.                 CMD
  5.                 ___
  6.  
  7.  
  8.  
  9. 1.0  OVERVIEW
  10.  
  11. The CMD package makes it very easy for  MACRO  programs  use
  12. the  COMND JSYS in order to provide the MACRO program's user
  13. to be able to type TOPS20 style  commands  to  the  program,
  14. including  all standard TOPS20 features such as recognition,
  15. question mark, CTRL/H etc.
  16.  
  17. The  CMD  package  is  a  valuable  tool  several   reasons,
  18. uncluding:
  19.  
  20. 1)      The programmer needn't allocate  any  special  COMND
  21.         JSYS buffers and blocks.
  22.  
  23. 2)      The programmer needn't provide  initialization  code
  24.         to set up pointers and blocks for the COMND JSYS.
  25.  
  26. 3)      The  programmer  needn't  provide  special  code  to
  27.         handle  "cleaning  up" associated with reparsing and
  28.         error returns.
  29.  
  30. In general, all the program  must  do  when  using  CMD,  is
  31. supply  the  field-specific data for the individual parts of
  32. the command being parsed.  CMD does most of the rest.
  33.  
  34.  
  35.  
  36. 2.0  NONGOAL
  37.  
  38. The CMD package does not attempt to provide  any  method  of
  39. generating  entire  command  languages,  such  as  structure
  40. trees.  It only provides primitives from which  such  things
  41. as structure trees may be designed.
  42.  
  43.  
  44.  
  45. 3.0  SAMPLE RUN
  46.  
  47. The following is a typescript of the running  of  a  program
  48. called CMTEST, which features two commands, EXIT and RENAME.
  49. The program uses the CMD package.
  50.  
  51. @RUN CMTEST
  52. CMTEST>? ONE OF THE FOLLOWING:
  53.  EXIT     RENAME
  54. CMTEST>RENAME (EXISTING FILE) FOO.ERT.1 (TO BE) ZOT.BAR
  55. CMTEST>EXIT ? CONFIRM WITH CARRIAGE RETURN
  56. CMTEST>EXIT 
  57. @
  58.                                                       Page 2
  59.  
  60.  
  61. 4.0  PROGRAM LISTING
  62.  
  63. The following program listing shows how the CMD  package  is
  64. utilized to implement commands.
  65.  
  66. title CMTEST
  67. search monsym,macsym,CMD
  68. .require sys:macrel,sys:CMD
  69.  
  70. beg:    RESET
  71.         MOVEI P,PDL-1                   ;SET UP STACK
  72.         CALL CMDINI                     ;INITIALIZE COMND JSYS
  73. LUP:    PROMPT (CMTEST>)                ;PROMPT FOR COMMAND
  74.         MOVEI A,[FLDDB. .CMKEY,,WRDLST] ;SPECIFY WE WANT A KEYWORD
  75.         CALL RFIELD                     ;READ COMMAND
  76.         MOVE A,(B)                      ;GET ADDRESS OF COMMAND ROUTINE
  77.         CALL (A)                        ;EXECUTE THE COMMAND
  78.         JRST LUP                        ;GO GET NEXT COMMAND
  79.  
  80. .EXIT:  CONFRM                          ;WAIT FOR END OF LINE
  81.         HALTF                           ;EXIT COMMAND CAUSES STOP
  82.         RET                             ;GET NEXT COMMAND IF CONTINUE
  83.  
  84. .RENAM: NOISE (EXISTING FILE)
  85.         MOVEI A,[FLDDB. .CMIFI]         ;SPECIFY INPUT FILE
  86.         CALL RFIELD                     ;GET FILE NAME BEING RENAMED
  87.         MOVEM B,IJFN                    ;REMEMBER IT
  88.         NOISE (TO BE)
  89.         MOVEI A,[FLDDB. .CMOFI]         ;SPECIFY OUTPUT FILE
  90.         CALL CFIELD                     ;GET NEW NAME AND END OF COMMAND
  91.         MOVEM B,OJFN
  92.         MOVE A,IJFN                     ;GET OLD NAME
  93.         RNAMF                           ;RENAME THE FILE
  94.          JSERR                          ;REPORT IF ERROR
  95.         MOVE A,OJFN                     ;GET RID OF JFN
  96.         RLJFN
  97.          JSERR                          ;REPORT IF ERROR
  98.         RET                             ;GO BACK FOR NEXT COMMAND
  99.  
  100. wrdlst: n,,n
  101.         t EXIT
  102.         T RENAME
  103. n==.-wrdlst-1
  104.  
  105. CMDSTG                                  ;ALLOCATE COMND JSYS STORAGE
  106. IJFN:   0                               ;INPUT FILE
  107. OJFN:   0                               ;OUTPUT FILE
  108. PDL:    BLOCK 200                       ;STACK SPACE
  109.  
  110. END BEG
  111.                                                       Page 3
  112.  
  113.  
  114. 5.0  SPECIFIC FEATURES AVAILABLE WITH CMD
  115.  
  116. 5.1  Telling MACRO And LINK That You Are Using The Package
  117.  
  118. Include the following two statements near the  beginning  of
  119. your source code.
  120.  
  121.         SEARCH CMD
  122.         .REQUIRE SYS:CMD
  123.  
  124. These two statements make the CMD package available to  your
  125. program.
  126.  
  127.  
  128.  
  129. 5.2  Initializing Your Program To Input Commands
  130.  
  131. Before prompting for  the  first  command  in  the  program,
  132. execute the following call:
  133.  
  134.         CALL CMDINI
  135.  
  136. The CMDINI routine should be called only once per running of
  137. the program.
  138.  
  139.  
  140.  
  141. 5.3  Allocating Storage For The Command Database
  142.  
  143. The following statement causes the database  for  the  COMND
  144. JSYS to be reserved.
  145.  
  146.         CMDSTG
  147.  
  148. Put this statement somewhere in your variable area  of  your
  149. program.
  150.  
  151.  
  152.  
  153. 5.4  Prompting For A Command
  154.  
  155. To prompt for a command, or new line of a command,  use  the
  156. PROMPT macro, like this:
  157.  
  158.         PROMPT (FOO)
  159.  
  160. The PROMPT macro causes the text in parentheses to be output
  161. as the prompt for the command line.
  162.                                                       Page 4
  163.  
  164.  
  165. 5.5  Reading A Field Of A Command
  166.  
  167. Load AC1 with the address of a COMND JSYS function block and
  168. call the RFIELD routine.  The following example shows how to
  169. read an input filespec:
  170.  
  171.         MOVEI A,[FLDDB. .CMIFI]
  172.         CALL RFIELD
  173.  
  174. The RFIELD routine returns with the result of the COMND JSYS
  175. in  AC1  and  AC2.   For  the  above example, a JFN would be
  176. returned in AC2.  The RFIELD  routine  handles  all  details
  177. such as reparsing and errors.
  178.  
  179.  
  180.  
  181. 5.6  Inputting The End Of The Command
  182.  
  183. To  require  the  typist  to  end  the  command  line  at  a
  184. particular point, use the CONFRM macro, like this:
  185.  
  186.         CONFRM
  187.  
  188.  
  189.  
  190.  
  191. 5.7  Inputting A Field Of A Command Followed By End Of Line
  192.  
  193. Since it is common to input a field followed by end of line,
  194. the  CFIELD  routine  is  supplied,  which  is  exactly like
  195. RFIELD, except it inputs end of line after the  field.   The
  196. call is as follows:
  197.  
  198.         CALL CFIELD
  199.  
  200.  
  201.  
  202. 5.8  Guide Words
  203.  
  204. To put guide words in a command, make the following call:
  205.  
  206.         NOISE (words)
  207.  
  208. The NOISE macro causes whatever text is in  the  parentheses
  209. to be used as the guide words.
  210.  
  211.  
  212.  
  213. 5.9  Keyword Table Entries
  214.  
  215. A macro called T is available to make it  easy  to  assemble
  216. keyword table entries.  The format is
  217.  
  218.         T word,data
  219.                                                       Page 5
  220.  
  221.  
  222. where "word" is the keyword, and "data" is specific data for
  223. the  keyword.   The  T  macro creates a word in memory whose
  224. left half points to the ASCIZ representation  of  the  word,
  225. and whose right half points to a word containing the data.
  226.  
  227. The "data" argument  defaults  to  ".word".   Hence  in  the
  228. common  case,  where the data for a keyword is the macro tag
  229. for the suuport code for that keyword, the call may be given
  230. like this:
  231.  
  232.         T word
  233.  
  234. This call requires you to have  the  support  code  for  the
  235. specified word elsewhere in your program, like this:
  236.  
  237. .word:  code
  238.         .   .   .
  239.         .   .   .
  240.         .   .   .
  241.  
  242.  
  243.  
  244.  
  245. 5.10  Special Other Details
  246.  
  247. The FLDDB.  macro (defined  in  MONSYM),  and  the  chaining
  248. facility  of  function  descriptor blocks generally provides
  249. enough  flexibility  for  creativity  of  command   language
  250. designs.   However,  for  the more devious, the following is
  251. revealed:
  252.  
  253.  
  254.  
  255. 5.10.1  Error Processing - If a user error is made, the  CMD
  256. module  normally prints an error message and allows the user
  257. to correct the mistake (with ^H) or issue  another  command.
  258. If you want your program to do its own error processing, you
  259. may call a routine called RFLDE instead  of  RFIELD.   RFLDE
  260. has an error return, like this:
  261.  
  262.         CALL RFLDE
  263.          ;+1 return means error
  264.         ;+2 return means success
  265.  
  266. Your error return should transfer off to code  which  prints
  267. some  sort  of error message.  Then transfer to CMDER1, like
  268. this:
  269.  
  270.         JRST CMDER1
  271.  
  272. CMDER1 takes responsibility for reprompting for the  command
  273. line  on  which  the error occured, and allowing the user to
  274. correct or retype the erroneous line.
  275.                                                       Page 6
  276.  
  277.  
  278. 5.10.2  GTJFN Block - The GTJFN  argument  block  is  called
  279. CJFNBK.   Note that to set up a default filespec, you merely
  280. need to put a pointer to the default spec  in  the  function
  281. descriptor block, so for setting up defaults, you don't need
  282. to explicitly reference CJFNBK.
  283.  
  284.  
  285.  
  286. 5.10.3  Command State Block - The COMND JSYS's command state
  287. block  is  called SBK.  Since the CMDINI routine sets it up,
  288. you normally shouldn't have to reference it.
  289.  
  290.  
  291.  
  292. 5.10.4  Custom Prompting - Sometimes,  the  prompt   for   a
  293. command  wants  to  be  computed  during  the running of the
  294. program.  For instance, a game program might want to type
  295.  
  296.         YOUR FIFTH MOVE:
  297.  
  298. as its prompt.   For  this  case,  the  PROMPT  macro  isn't
  299. sufficient.
  300.  
  301. The general  prompting  routine  is  call  DPROMPT.   It  is
  302. important  that  your  program  call  it,  or use the PROMPT
  303. macro.  Otherwise, reparsing (the magic  that  happens  when
  304. typist  deletes  parsed  characters) won't happen correctly.
  305. That is, don't just call RFIELD with the .CMINI function!
  306.  
  307. For the above example, suppose the game program had  created
  308. the desired string and stored it in an area of memory tagged
  309. with MOVMES.  The program may type the prompt like this:
  310.  
  311.         HRROI A,MOVMES
  312.         CALL DPROMPT
  313.  
  314. The DPROMPT routine assumes A  contains  a  pointer  to  the
  315. prompt string.
  316.